
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>CMP0114 &mdash; CMake 3.27.4 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />
    
    <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/sphinx_highlight.js"></script>
    
    <link rel="shortcut icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMP0113" href="CMP0113.html" />
    <link rel="prev" title="CMP0115" href="CMP0115.html" />
 

  </head><body>

    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="CMP0113.html" title="CMP0113"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="CMP0115.html" title="CMP0115"
             accesskey="P">previous</a> |</li>
  <li>
    <img src="../_static/cmake-logo-16.png" alt=""
         style="vertical-align: middle; margin-top: -2px" />
  </li>
  <li>
    <a href="https://cmake.org/">CMake</a> &#187;
  </li>
  <li>
    <a href="../index.html">3.27.4 Documentation</a> &#187;
  </li>

          <li class="nav-item nav-item-1"><a href="../manual/cmake-policies.7.html" accesskey="U">cmake-policies(7)</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">CMP0114</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="cmp0114">
<span id="policy:CMP0114"></span><h1>CMP0114<a class="headerlink" href="#cmp0114" title="Permalink to this heading">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.19.</span></p>
</div>
<p><span class="target" id="index-0-module:ExternalProject"></span><a class="reference internal" href="../module/ExternalProject.html#module:ExternalProject" title="ExternalProject"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">ExternalProject</span></code></a> step targets fully adopt their steps.</p>
<p>The <span class="target" id="index-0-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> <code class="docutils literal notranslate"><span class="pre">STEP_TARGETS</span></code> option, and the
<span class="target" id="index-0-command:externalproject_add_steptargets"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add_steptargets" title="externalproject_add_steptargets"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add_StepTargets()</span></code></a> function, can be used to
create build targets for individual steps of an external project.</p>
<p>In CMake 3.18 and below, step targets have some limitations:</p>
<ul>
<li><p>Step targets always depend on targets named by the
<span class="target" id="index-1-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> <code class="docutils literal notranslate"><span class="pre">DEPENDS</span></code> option even though
not all steps need them.  In order to allow step targets to be created
without those dependencies, the <span class="target" id="index-2-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a>
<code class="docutils literal notranslate"><span class="pre">INDEPENDENT_STEP_TARGETS</span></code> option or the
<span class="target" id="index-1-command:externalproject_add_steptargets"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add_steptargets" title="externalproject_add_steptargets"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add_StepTargets()</span></code></a> <code class="docutils literal notranslate"><span class="pre">NO_DEPENDS</span></code> option may
be used.  However, adding such &quot;independent&quot; step targets makes sense
only for specific steps such as <code class="docutils literal notranslate"><span class="pre">download</span></code>, <code class="docutils literal notranslate"><span class="pre">update</span></code>, and <code class="docutils literal notranslate"><span class="pre">patch</span></code>
because they do not need any of the external project's build dependencies.
Furthermore, it does not make sense to create independent step targets
for steps that depend on non-independent steps.  Such rules are not
enforced, and projects that do not follow them can generate build systems
with confusing and generator-specific behavior.</p></li>
<li><p>Step targets hold copies of the custom commands implementing their
steps that are separate from the copies in the primary target created
by <span class="target" id="index-3-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a>, and the primary target does not
depend on the step targets.  In parallel builds that drive the primary
target and step targets concurrently, multiple copies of the steps'
commands may run concurrently and race each other.</p>
<p>Also, prior to policy <span class="target" id="index-0-policy:CMP0113"></span><a class="reference internal" href="CMP0113.html#policy:CMP0113" title="CMP0113"><code class="xref cmake cmake-policy docutils literal notranslate"><span class="pre">CMP0113</span></code></a>, the step targets generated
by <a class="reference internal" href="../manual/cmake-generators.7.html#makefile-generators"><span class="std std-ref">Makefile Generators</span></a> also contain all the custom commands
on which their step depends.  This can lead to repeated execution of
those steps even in serial builds.</p>
</li>
</ul>
<p>In CMake 3.19 and above, the <span class="target" id="index-1-module:ExternalProject"></span><a class="reference internal" href="../module/ExternalProject.html#module:ExternalProject" title="ExternalProject"><code class="xref cmake cmake-module docutils literal notranslate"><span class="pre">ExternalProject</span></code></a> module prefers
a revised design to address these problems:</p>
<ul>
<li><p>Each step is classified as &quot;independent&quot; if it does not depend
on other targets named by the <span class="target" id="index-4-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> <code class="docutils literal notranslate"><span class="pre">DEPENDS</span></code>.
The predefined steps are automatically classified by default:</p>
<ul class="simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">download</span></code>, <code class="docutils literal notranslate"><span class="pre">update</span></code>, and <code class="docutils literal notranslate"><span class="pre">patch</span></code> steps are independent.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">configure</span></code>, <code class="docutils literal notranslate"><span class="pre">build</span></code>, <code class="docutils literal notranslate"><span class="pre">test</span></code>, and <code class="docutils literal notranslate"><span class="pre">install</span></code> steps are not.</p></li>
</ul>
<p>For custom steps, the <span class="target" id="index-0-command:externalproject_add_step"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add_step" title="externalproject_add_step"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add_Step()</span></code></a> command provides
an <code class="docutils literal notranslate"><span class="pre">INDEPENDENT</span></code> option to mark them as independent.  It is an error to
mark a step as independent if it depends on other steps that are not.  Note
that this use of the term &quot;independent&quot; refers only to independence from
external targets and is orthogonal to a step's dependencies on other steps.</p>
</li>
<li><p>Step targets created by the <span class="target" id="index-5-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> <code class="docutils literal notranslate"><span class="pre">STEP_TARGETS</span></code>
option or the <span class="target" id="index-1-command:externalproject_add_step"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add_step" title="externalproject_add_step"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add_Step()</span></code></a> function are now
independent if and only if their steps are marked as independent.
The <span class="target" id="index-6-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> <code class="docutils literal notranslate"><span class="pre">INDEPENDENT_STEP_TARGETS</span></code> option
and <span class="target" id="index-2-command:externalproject_add_steptargets"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add_steptargets" title="externalproject_add_steptargets"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add_StepTargets()</span></code></a> <code class="docutils literal notranslate"><span class="pre">NO_DEPENDS</span></code> option
are no longer allowed.</p></li>
<li><p>Step targets, when created, are fully responsible for holding the
custom commands implementing their steps.  The primary target created
by <span class="target" id="index-7-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> depends on the step targets, and the
step targets depend on each other.  The target-level dependencies match
the file-level dependencies used by the custom commands for each step.</p>
<p>When the <span class="target" id="index-8-command:externalproject_add"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add" title="externalproject_add"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add()</span></code></a> <code class="docutils literal notranslate"><span class="pre">UPDATE_DISCONNECTED</span></code> or
<code class="docutils literal notranslate"><span class="pre">TEST_EXCLUDE_FROM_MAIN</span></code> option is used, or the
<span class="target" id="index-2-command:externalproject_add_step"></span><a class="reference internal" href="../module/ExternalProject.html#command:externalproject_add_step" title="externalproject_add_step"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">ExternalProject_Add_Step()</span></code></a> <code class="docutils literal notranslate"><span class="pre">EXCLUDE_FROM_MAIN</span></code> option is used
for a custom step, some step targets may be created automatically.
These are needed to hold the steps commonly depended upon by the primary
target and the disconnected step targets.</p>
</li>
</ul>
<p>Policy <code class="docutils literal notranslate"><span class="pre">CMP0114</span></code> provides compatibility for projects that have not been
updated to expect the new behavior.  The <code class="docutils literal notranslate"><span class="pre">OLD</span></code> behavior for this policy
is to use the above-documented behavior from 3.18 and below.  The <code class="docutils literal notranslate"><span class="pre">NEW</span></code>
behavior for this policy is to use the above-documented behavior preferred
by 3.19 and above.</p>
<p>This policy was introduced in CMake version 3.19.  CMake version
3.27.4 warns when the policy is not set and uses <code class="docutils literal notranslate"><span class="pre">OLD</span></code> behavior.
Use the <span class="target" id="index-0-command:cmake_policy"></span><a class="reference internal" href="../command/cmake_policy.html#command:cmake_policy" title="cmake_policy"><code class="xref cmake cmake-command docutils literal notranslate"><span class="pre">cmake_policy()</span></code></a> command to set it to <code class="docutils literal notranslate"><span class="pre">OLD</span></code> or <code class="docutils literal notranslate"><span class="pre">NEW</span></code>
explicitly.</p>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="CMP0115.html"
                          title="previous chapter">CMP0115</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="CMP0113.html"
                          title="next chapter">CMP0113</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/policy/CMP0114.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="CMP0113.html" title="CMP0113"
             >next</a> |</li>
        <li class="right" >
          <a href="CMP0115.html" title="CMP0115"
             >previous</a> |</li>
  <li>
    <img src="../_static/cmake-logo-16.png" alt=""
         style="vertical-align: middle; margin-top: -2px" />
  </li>
  <li>
    <a href="https://cmake.org/">CMake</a> &#187;
  </li>
  <li>
    <a href="../index.html">3.27.4 Documentation</a> &#187;
  </li>

          <li class="nav-item nav-item-1"><a href="../manual/cmake-policies.7.html" >cmake-policies(7)</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">CMP0114</a></li> 
      </ul>
    </div>

    <div class="footer" role="contentinfo">
        &#169; Copyright 2000-2023 Kitware, Inc. and Contributors.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
    </div>
  </body>
</html>